// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

[
  {
    "namespace": "i18n",
    "description": "Use the <code>chrome.i18n</code> infrastructure to implement internationalization across your whole app or extension.",
    "types": [
      {
        "id": "LanguageCode",
        "type": "string",
        "description": "An ISO language code such as <code>en</code> or <code>fr</code>. For a complete list of languages supported by this method, see <a href='http://src.chromium.org/viewvc/chrome/trunk/src/third_party/cld/languages/internal/languages.cc'>kLanguageInfoTable</a>. For an unknown language, <code>und</code> will be returned, which means that [percentage] of the text is unknown to CLD"
      }
    ],
    "functions": [
      {
        "name": "getAcceptLanguages",
        "type": "function",
        "description": "Gets the accept-languages of the browser. This is different from the locale used by the browser; to get the locale, use $(ref:i18n.getUILanguage).",
        "parameters": [],
        "returns_async": {
          "name": "callback",
          "parameters": [
            {"name": "languages", "type": "array", "items": {"$ref": "LanguageCode"}, "description": "Array of LanguageCode"}
          ]
        }
      },
      {
        "name": "getMessage",
        "nocompile": true,
        "type": "function",
        "description": "Gets the localized string for the specified message. If the message is missing, this method returns an empty string (''). If the format of the <code>getMessage()</code> call is wrong &mdash; for example, <em>messageName</em> is not a string or the <em>substitutions</em> array has more than 9 elements &mdash; this method returns <code>undefined</code>.",
        "parameters": [
          {
            "type": "string",
            "name": "messageName",
            "description": "The name of the message, as specified in the <a href='how-to/ui/localization-message-formats'><code>messages.json</code></a> file."
          },
          {
            "type": "any",
            "name": "substitutions",
            "optional": true,
            "description": "Up to 9 substitution strings, if the message requires any."
          },
          {
            "type": "object",
            "name": "options",
            "optional": true,
            "properties": {
              "escapeLt": {
                "type": "boolean",
                "optional": true,
                "description": "Escape <code>&lt;</code> in translation to <code>&amp;lt;</code>. This applies only to the message itself, not to the placeholders. Developers might want to use this if the translation is used in an HTML context. Closure Templates used with Closure Compiler generate this automatically."
              }
            }
          }
        ],
        "returns": {
          "type": "string",
          "description": "Message localized for current locale."
        }
      },
      {
        "name": "getUILanguage",
        "type": "function",
        "nocompile": true,
        "description": "Gets the browser UI language of the browser. This is different from $(ref:i18n.getAcceptLanguages) which returns the preferred user languages.",
        "parameters": [],
        "returns": {
          "type": "string",
          "description": "The browser UI language code such as en-US or fr-FR."
        }
      },
      {
        "name": "detectLanguage",
        "type": "function",
        "nocompile": true,
        "description": "Detects the language of the provided text using CLD.",
        "parameters": [
          {
            "type": "string",
            "name": "text",
            "minimum": 0,
            "description": "User input string to be translated."
          }
        ],
        "returns_async": {
          "name": "callback",
          "parameters": [
            {
              "type": "object",
              "name": "result",
              "description": "LanguageDetectionResult object that holds detected langugae reliability and array of DetectedLanguage",
              "properties": {
                "isReliable": { "type": "boolean", "description": "CLD detected language reliability" },
                "languages":
                  {
                    "type": "array",
                    "description": "array of detectedLanguage",
                    "items":
                      {
                        "type": "object",
                        "description": "DetectedLanguage object that holds detected ISO language code and its percentage in the input string",
                        "properties":
                          {
                            "language":
                              {
                                "$ref": "LanguageCode"
                              },
                            "percentage":
                              {
                                "type": "integer",
                                "description": "The percentage of the detected language"
                              }
                          }
                      }
                  }
              }
            }
          ]
        }
      }
    ],
    "events": []
  }
]